Repository navigation
Mkdocs - #74
Mkdocs#74
Conversation
There was a problem hiding this comment.
Pull request overview
This PR migrates the documentation system from Sphinx to MkDocs Material, modernizing the documentation infrastructure and converting all documentation files from reStructuredText (RST) to Markdown format.
Key Changes:
- Replaces Sphinx documentation system with MkDocs Material
- Converts all RST documentation files to Markdown format
- Updates documentation generation to output protobuf definitions as Markdown instead of HTML
- Restructures GitHub Actions workflow for MkDocs-based deployment
Reviewed changes
Copilot reviewed 30 out of 33 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| src/compas_pb/invocations.py | Modified docs task to generate markdown protobuf docs and build with mkdocs instead of Sphinx |
| pyproject.toml | Added new [docs] optional dependency group with MkDocs packages; moved dependencies from dynamic loading to inline declarations |
| requirements-dev.txt | Added mkdocs, mkdocs-material, and mkdocstrings dependencies (creates duplication with pyproject.toml) |
| mkdocs.yml | New MkDocs configuration file with Material theme, plugins, and navigation structure |
| .github/workflows/docs.yml | Replaced compas-actions.docs workflow with custom mkdocs deployment steps |
| docs/*.md | New Markdown documentation files replacing RST versions (index, installation, examples, introduction, license, missing_compas_type) |
| docs/*.rst | Old RST documentation files being removed |
| docs/reference/*.md | New API reference pages using mkdocstrings for auto-documentation |
| docs/protobuf.md | Auto-generated protobuf documentation in Markdown format (1295 lines) |
| docs/assets/images/* | Logo images (SVG and PNG) for the documentation site |
| docs(ctx, doctest, rebuild, check_links) | ||
| dist_dir = Path(ctx.base_folder) / "dist" | ||
|
|
||
| ctx.run(f"mkdocs build -c -d {dist_dir} -t material") |
There was a problem hiding this comment.
The -t material flag is invalid for mkdocs build. The theme is already specified in mkdocs.yml (line 15: name: material). The -t flag doesn't exist in mkdocs CLI.
Remove the -t material flag from the command:
ctx.run(f"mkdocs build -c -d {dist_dir}")|
|
||
| - name: Install dependencies | ||
| run: | | ||
| pip install -e .[dev] |
There was a problem hiding this comment.
The GitHub Actions workflow installs dependencies with pip install -e .[dev] but MkDocs dependencies are in the separate [docs] optional dependency group (defined in pyproject.toml lines 52-68). This will cause the workflow to fail because mkdocs and related packages won't be installed.
Change the installation command to include the docs dependencies:
pip install -e .[dev,docs]| pip install -e .[dev] | |
| pip install -e .[dev,docs] |
| mkdocs | ||
| mkdocs-material | ||
| mkdocstrings[python] |
There was a problem hiding this comment.
The requirements-dev.txt file now contains MkDocs-related dependencies (lines 12-14), but these have also been added to the [project.optional-dependencies.docs] section in pyproject.toml. Since pyproject.toml no longer dynamically loads from requirements-dev.txt (the dynamic loading was removed in lines 89-90), this creates duplication and potential version conflicts.
Consider either:
- Remove mkdocs dependencies from
requirements-dev.txtsince they're already inpyproject.tomlunder[docs] - Or add them to the
[dev]section inpyproject.tomlif they should be part of dev dependencies
The typical pattern is to have documentation dependencies separate from development dependencies.
| text: Roboto | ||
| code: Roboto Mono | ||
| logo: assets/images/compas_pb.png | ||
| favicon: public/favicon.ico |
There was a problem hiding this comment.
The favicon path references public/favicon.ico but this file/directory doesn't exist in the repository. This will cause a 404 error when the documentation site tries to load the favicon.
Either:
- Create a
docs/public/favicon.icofile - Remove the favicon line if not needed
- Or use an existing image file like
docs/assets/images/compas_pb.png
Example fix:
favicon: assets/images/compas_pb.png| favicon: public/favicon.ico | |
| favicon: assets/images/compas_pb.png |
| "compas_invocations2", | ||
| "invoke >=0.14", | ||
| "ruff", | ||
| "sphinx_compas2_theme", |
There was a problem hiding this comment.
The sphinx_compas2_theme package is still listed in the [dev] dependencies but it's only used for Sphinx documentation. Since the project has migrated to MkDocs, this dependency is no longer needed and should be removed to avoid installing unnecessary packages.
| version: | ||
| provider: mike |
There was a problem hiding this comment.
The mkdocs.yml configures mike as the version provider (lines 11-12), but the GitHub Actions workflow uses mkdocs gh-deploy instead of mike deploy. This creates an inconsistency - either the workflow should use mike for versioned deployments, or the mike configuration should be removed from mkdocs.yml.
If versioning is desired, the workflow should use:
- name: Deploy to GitHub Pages
run: |
mike deploy --push --update-aliases $VERSION latestIf versioning is not needed, remove the version provider configuration from mkdocs.yml.
| version: | |
| provider: mike |
| # intercepting the `invoke docs` call so that the protobuf docs are generated first | ||
| # the single html file is linked to from the main docs site |
There was a problem hiding this comment.
The comment mentions "the single html file" but the output is now a Markdown file (protobuf.md), not an HTML file. Update the comment to reflect the actual output format:
# the markdown file is linked to from the main docs site|
Why that color? I thought that purple-ish was just a default color for testing it, but we would change it to the COMPAS blue before we go live on any of these themes |
| theme: | ||
| name: material | ||
| palette: | ||
| scheme: slate | ||
| primary: indigo | ||
| accent: indigo |
There was a problem hiding this comment.
We can use custom css if we have it.
https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#customization
Migrated the documentation to mkdocs material from sphinx
@zeitunik ;)
What type of change is this?
Checklist
Put an
xin the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.CHANGELOG.mdfile in theUnreleasedsection under the most fitting heading (e.g.Added,Changed,Removed).invoke test).invoke lint).compas.datastructures.Mesh.